<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Defining application-specific log records</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="apprec.html" title="Chapter 16.  Application Specific Logging and Recovery" />
    <link rel="prev" href="apprec.html" title="Chapter 16.  Application Specific Logging and Recovery" />
    <link rel="next" href="apprec_auto.html" title="Automatically generated functions" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Defining application-specific log
        records</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="apprec.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 16.  Application Specific Logging and
        Recovery </th>
          <td width="20%" align="right"> <a accesskey="n" href="apprec_auto.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="apprec_def"></a>Defining application-specific log
        records</h2>
          </div>
        </div>
      </div>
      <p>
        By convention, log records are described in files named
        <code class="filename">XXX.src</code>, where "XXX" is typically a
        descriptive name for a subsystem or other logical group of
        logging functions. These files contain interface definition
        language descriptions for each type of log record that is used
        by the subsystem.
    </p>
      <p>
        All blank lines and lines beginning with a hash ("#")
        character in the XXX.src files are ignored.
    </p>
      <p>
        The first non-comment line in the file should begin with the
        keyword PREFIX, followed by a string that will be prepended to
        every generated function name. Frequently, the PREFIX is
        either identical or similar to the name of the
        <code class="filename">XXX.src</code> file. For example, the
        Berkeley DB application-specific recovery example uses the
        file <code class="filename">ex_apprec.src</code>, which begins with the
        following PREFIX line:
    </p>
      <pre class="programlisting">PREFIX ex_apprec</pre>
      <p>
        Following the PREFIX line are the include files required by
        the automatically generated functions. The include files
        should be listed in order, prefixed by the keyword INCLUDE.
        For example, the Berkeley DB application-specific recovery
        example lists the following include files:
    </p>
      <pre class="programlisting">INCLUDE #include "ex_apprec.h"</pre>
      <p>
        The rest of the XXX.src file consists of log record
        descriptions. Each log record description begins with one of
        the following lines:
    </p>
      <pre class="programlisting">BEGIN <span class="emphasis"><em>RECORD_NAME</em></span> <span class="emphasis"><em>DB_VERSION_NUMBER</em></span> <span class="emphasis"><em>RECORD_NUMBER</em></span></pre>
      <pre class="programlisting">BEGIN_COMPAT <span class="emphasis"><em>RECORD_NAME</em></span> <span class="emphasis"><em>DB_VERSION_NUMBER</em></span> <span class="emphasis"><em>RECORD_NUMBER</em></span></pre>
      <p>
        and ends with the line:
    </p>
      <pre class="programlisting">END</pre>
      <p>
        The <span class="emphasis"><em>BEGIN</em></span> line should be used for most
        record types.
    </p>
      <p>
        The <span class="emphasis"><em>BEGIN_COMPAT</em></span> is used for log record
        compatibility to facilitate online upgrades of replication
        groups. Records created with this keyword will produce reading
        and printing routines, but no logging routines. The recovery
        routines are retrieved from older releases, so no recovery
        templates will be generated for these records.
    </p>
      <p>
        The <span class="emphasis"><em>DB_VERSION_NUMBER</em></span> variable should
        be replaced with the current major and minor version of
        Berkeley DB, with all punctuation removed. For example,
        Berkeley DB version 4.2 should be 42, version 4.5 should be
        45.
    </p>
      <p>
        The <span class="emphasis"><em>RECORD_NAME</em></span> variable should be
        replaced with a record name for this log record. The
        <span class="emphasis"><em>RECORD_NUMBER</em></span> variable should be
        replaced with a record number.
    </p>
      <p>
        The combination of PREFIX name and
        <span class="emphasis"><em>RECORD_NAME</em></span>, and the
        <span class="emphasis"><em>RECORD_NUMBER</em></span> must be unique for the
        application, that is, values for application-specific and
        Berkeley DB log records may not overlap. Further, because
        record numbers are stored in log files, which are usually
        portable across application and Berkeley DB releases, any
        change to the record numbers or log record format or should be
        handled as described in the section on log format changes in
        the <a href="../upgrading/upgrade_process.html" class="olink">Upgrading Berkeley DB installations</a> chapter of the Berkeley DB Installation and Build Guide. The record
        number space below 10,000 is reserved for Berkeley DB itself;
        applications should choose record number values equal to or
        greater than 10,000.
    </p>
      <p>
        Between the BEGIN and END keywords there should be one
        optional <span class="emphasis"><em>DUPLICATE</em></span> line and one line for
        each data item logged as part of this log record.</p>
      <p>
        The <span class="emphasis"><em>DUPLICATE</em></span> line is of the
        form:
    </p>
      <pre class="programlisting">DUPLICATE <span class="emphasis"><em>RECORD_NAME</em></span> <span class="emphasis"><em>DB_VERSION_NUMBER</em></span> <span class="emphasis"><em>RECORD_NUMBER</em></span></pre>
      <p>
        The <span class="emphasis"><em>DUPLICATE</em></span> specifier should be used
        when creating a record that requires its own record number but
        can use the argument structure, reading and printing routines
        from another record. In this case, we will create a new log
        record type, but use the enclosing log record type for the
        argument structure and the log reading and printing
        routines.
    </p>
      <p>
        The format of lines for each data item logged is as
        follows:
    </p>
      <pre class="programlisting">ARG | DBT | POINTER <span class="emphasis"><em>variable_name</em></span> <span class="emphasis"><em>variable_type</em></span> <span class="emphasis"><em>printf_format</em></span></pre>
      <p>
        The keyword ARG indicates that the argument is a simple
        parameter of the type specified. For example, a file ID might
        be logged as:
    </p>
      <pre class="programlisting">ARG fileID int d</pre>
      <p>
        The keyword DBT indicates that the argument is a Berkeley DB
        DBT structure, containing a length and pointer to a byte
        string. The keyword POINTER indicates that the argument is a
        pointer to the data type specified (of course the data type,
        not the pointer, is what is logged).
    </p>
      <p>
        The <span class="emphasis"><em>variable_name</em></span> is the field name
        within the structure that will be used to refer to this item.
        The <span class="emphasis"><em>variable_type</em></span> is the C-language type
        of the variable, and the printf format is the C-language
        format string, without the leading percent ("%") character,
        that should be used to display the contents of the field (for
        example, "s" for string, "d" for signed integral type, "u" for
        unsigned integral type, "ld" for signed long integral type,
        "lu" for long unsigned integral type, and so on).
    </p>
      <p>
        For example, ex_apprec.src defines a single log record type,
        used to log a directory name that has been stored in a
        DBT:
    </p>
      <pre class="programlisting">BEGIN	mkdir		10000
DBT	dirname		DBT		s
END</pre>
      <p>
        As the name suggests, this example of an application-defined
        log record will be used to log the creation of a directory.
        There are many more examples of XXX.src files in the Berkeley
        DB distribution. For example, the file btree/btree.src
        contains the definitions for the log records supported by the
        Berkeley DB Btree access method.
    </p>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="apprec.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="apprec.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="apprec_auto.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Chapter 16.  Application Specific Logging and
        Recovery  </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Automatically generated
        functions</td>
        </tr>
      </table>
    </div>
  </body>
</html>
